File Procedures

Assorted file, folder and path procedures.

Include files: AfxWin.inc, AfxPath.inc

Dialogs

File and Folder Procedures

Path and Url Procedures

AfxBrowseForFolder

Displays a dialog box that enables the user to select a folder.

FUNCTION AfxBrowseForFolder (BYVAL hwnd AS HWND, BYVAL pwszTitle AS WSTRING PTR = NULL, _
   BYVAL pwszStartFolder AS WSTRING PTR = NULL, BYVAL nFlags AS LONG = 0) AS CWSTR

Notes

If COM is initialized through CoInitializeEx with the COINIT_MULTITHREADED flag set, AfxShellBrowserForFolder fails if BIF_NEWDIALOGSTYLE or BIF_USENEWUI are passed.

Return value

The path of the selected folder.

Remarks

If you don't pass any flags, the function will use BIF_RETURNONLYFSDIRS OR BIF_DONTGOBELOWDOMAIN OR BIF_USENEWUI OR BIF_RETURNFSANCESTORS.

Usage example

DIM cws AS CWSTR = AfxBrowseForFolder(hwnd, "C:")

AfxOpenFileDialog

Creates an Open dialog box that lets the user specify the drive, directory, and the name of a file or set of files to be opened. The dialog box uses the Explorer-style user interface.

FUNCTION AfxOpenFileDialog (BYVAL hwndOwner AS HWND, BYREF wszTitle AS WSTRING, BYREF wszFile AS WSTRING, _
   BYREF wszInitialDir AS WSTRING, BYREF wszFilter AS WSTRING, BYREF wszDefExt AS WSTRING, _
   BYVAL pdwFlags AS DWORD PTR = NULL, BYVAL pdwBufLen AS DWORD PTR = NULL) AS CWSTR

Return value

If the OFN_ALLOWMULTISELECT flag is set and the user selects multiple files, the returned string contains the current directory followed by the file names of the selected files. For Explorer-style dialog boxes, the directory and file name strings are separated by semicolons. If the user selects only one file, the returned string does not have a separator between the path and file name.

Parse the number of ",". If only one, then the user has selected only a file and the string contains the full path. If more, The first substring contains the path and the others the files. If the user has not selected any file, an empty string is returned. On failure, an empty string is returned and, if not null, the pdwBufLen parameter will be filled by the size of the required buffer in characters.

Usage example:

DIM wszFile AS WSTRING * 260 = "*.*"
DIM wszInitialDir AS STRING * 260 = CURDIR
DIM wszFilter AS WSTRING * 260 = "BAS files (*.BAS)|*.BAS|" & "All Files (*.*)|*.*|"
DIM dwFlags AS DWORD = OFN_EXPLORER OR OFN_FILEMUSTEXIST OR OFN_HIDEREADONLY OR OFN_ALLOWMULTISELECT
DIM cws AS CWSTR = AfxOpenFileDialog(hwnd, "", wszFile, wszInitialDir, wszFilter, "BAS", @dwFlags, NULL)
AfxMsg cws

AfxSaveFileDialog

Creates a Save dialog box that lets the user specify the drive, directory, and name of a file to save. The dialog box uses the Explorer-style user interface.

FUNCTION AfxSaveFileDialog (BYVAL hwndOwner AS HWND, BYREF wszTitle AS WSTRING, BYREF wszFile AS WSTRING, _
   BYREF wszInitialDir AS WSTRING, BYREF wszFilter AS WSTRING, BYREF wszDefExt AS WSTRING, _
   BYVAL pdwFlags AS DWORD PTR = NULL) AS CWSTR

Return value

The path of the file to be saved.

Usage example:

DIM wszFile AS WSTRING * 260 = "*.*"
DIM wszInitialDir AS STRING * 260 = CURDIR
DIM wszFilter AS WSTRING * 260 = "BAS files (*.BAS)|*.BAS|" & "All Files (*.*)|*.*|"
DIM dwFlags AS DWORD = OFN_EXPLORER OR OFN_FILEMUSTEXIST OR OFN_HIDEREADONLY OR OFN_OVERWRITEPROMPT
DIM cws AS CWSTR = AfxSaveFileDialog(hwnd, "", wszFile, wszInitialDir, wszFilter, "BAS", @dwFlags)
AfxMsg cws

AfxChDir / AfxSetCurDir / AfxSetCurrentDirectory

Changes the current directory for the current process.

FUNCTION AfxChDir (BYVAL pwszPathName AS LPCWSTR) AS LONG
FUNCTION AfxSetCurDir (BYVAL pwszPathName AS LPCWSTR) AS BOOLEAN
FUNCTION AfxSetCurrentDirectory (BYVAL pwszPathName AS LPCWSTR) AS BOOLEAN

Return value for AfxChDir:

If the function succeeds, the return value is 0.
If the function fails, the return value is -1.
To get extended error information, call GetLastError.

AfxMkDir is an unicode replacement for Free Basic's MkDir.

Return value for AfxSetCurDir and AfxSetCurrentDirectory:

If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE.
To get extended error information, call GetLastError.

AfxCopyFile / AfxFileCopy

Copies an existing file to a new file.

FUNCTION AfxCopyFile (BYVAL lpExistingFileName AS LPCWSTR, BYVAL lpNewFileName AS LPCWSTR, _
   BYVAL bFailIfExists AS BOOLEAN = FALSE) AS BOOLEAN
FUNCTION AfxFileCopy (BYVAL lpExistingFileName AS LPCWSTR, BYVAL lpNewFileName AS LPCWSTR, _
   BYVAL bFailIfExists AS BOOLEAN = FALSE) AS BOOLEAN

Return value

If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Rermarks

AfxFileCopy is an unicode replacement for Free Basic's FileCopy and returns 0 on success, or 1 if an error occurred.

AfxMkDir / AfxMakeDir / AfxCreateDirectory

Creates a new directory.

FUNCTION AfxMkDir (BYVAL lpPathName AS LPCWSTR) AS LONG
FUNCTION AfxCreateDirectory (BYVAL lpPathName AS LPCWSTR) AS BOOLEAN
FUNCTION AfxMakeDir (BYVAL lpPathName AS LPCWSTR) AS BOOLEAN

Return value for AfxMkDir:

If the function succeeds, the return value is 0.
If the function fails, the return value is -1.
To get extended error information, call GetLastError.

AfxMkDir is an unicode replacement for Free Basic's MkDir.

Return value for AfxCreateDirectory and AfxMakeDir:

If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE.
To get extended error information, call GetLastError.

Possible errors include the following.

AfxDeleteFile / AfxKill

Deletes the specified file.

FUNCTION AfxDeleteFile (BYVAL pwszFileSpec AS WSTRING PTR) AS BOOLEAN
FUNCTION AfxKill (BYVAL pwszFileSpec AS WSTRING PTR) AS BOOLEAN

Return value:

If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE.
To get extended error information, call GetLastError.

Remarks

If an application attempts to delete a file that does not exist, this function fails with ERROR_FILE_NOT_FOUND. If the file is a read-only file, the function fails with ERROR_ACCESS_DENIED.

AfxKill is an unicode replacement for Free Basic's Kill and returns 0 on success, or -1 on failure.

AfxFileDateTime

Returns the file's last modified date and time as Date Serial.

FUNCTION AfxFileDateTime (BYREF wszFileName AS WSTRING) AS DOUBLE

Return value

The date and time as a Date Serial. If it fails, it returns 0.

Remark

Unicode replacement for Free Basic's FileDateTime.

Example

#include "windows.bi"
#include "vbcompat.bi"
#include "Afx/AfxWin.bi"
DIM wszFileName AS WSTRING * MAX_PATH = ExePath & "\c2.bas"
DIM dt AS DOUBLE = AfxFileDateTime(wszFileName)
PRINT Format(dt, "yyyy-mm-dd hh:mm AM/PM")

AfxCurdir / AfxGetCurDir / AfxGetCurrentDirectory

Retrieves the current directory for the current process.

FUNCTION AfxCurDir () AS CWSTR
FUNCTION AfxGetCurDir () AS CWSTR
FUNCTION AfxGetCurrentDirectory () AS CWSTR

Return value

The name of the current directory for the current process.

Remark

Unicode replacement for Free Basic's CurDir.

AfxName / AfxRenameFile / AfxMoveFile

Moves an existing file or a directory, including its children.

FUNCTION AfxName (BYVAL lpExistingFileName AS LPCWSTR, BYVAL lpNewFileName AS LPCWSTR) AS LONG
FUNCTION AfxRenameFile (BYVAL lpExistingFileName AS LPCWSTR, BYVAL lpNewFileName AS LPCWSTR) AS BOOLEAN
FUNCTION AfxMoveFile (BYVAL lpExistingFileName AS LPCWSTR, BYVAL lpNewFileName AS LPCWSTR) AS BOOLEAN

Return value for AfxName:

If the function succeeds, the return value is 0.
If the function fails, the return value is -1.
To get extended error information, call GetLastError.

AfxName is an unicode replacement for Free Basic's Name.

Return value for AfxRenameFile and AfxMoveFile:

If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE.
To get extended error information, call GetLastError.

AfxRmDir / AfxRemoveDir / AfxRemoveDirectory

Deletes an existing empty directory.

FUNCTION AfxRmDir (BYVAL lpPathName AS LPCWSTR) AS LONG
FUNCTION AfxRemoveDir (BYVAL lpPathName AS LPCWSTR) AS BOOLEAN
FUNCTION AfxRemoveDirectory (BYVAL lpPathName AS LPCWSTR) AS BOOLEAN

Return value for AfxRmDir:

If the function succeeds, the return value is 0.
If the function fails, the return value is -1.
To get extended error information, call GetLastError.

AfxRmDir is an unicode replacement for Free Basic's RmDir.

Return value for AfxRemoveDir and AfxRemoveDirectory:

If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE.
To get extended error information, call GetLastError.

Remaks

These functions mark a directory for deletion on close. Therefore, the directory is not removed until the last handle to the directory is closed. To recursively delete the files in a directory, use the SHFileOperation function.

AfxFileExists

Searches a directory for a file or subdirectory with a name that matches a specific name (or partial name if wildcards are used).

FUNCTION AfxFileExists (BYVAL pwszFileSpec AS WSTRING PTR) AS BOOLEAN

Return value

Boolean. TRUE if the specified file exist or FALSE otherwise.

Remarks

Prepending the string "\\?\" does not allow access to the root directory.

On network shares, you can use an pwszFileSpec in the form of the following: "\\server\service\*". However, you cannot use an pwszFileSpec that points to the share itself; for example, "\\server\service" is not valid.

To examine a directory that is not a root directory, use the path to that directory, without a trailing backslash. For example, an argument of "C:\Windows" returns information about the directory "C:\Windows", not about a directory or file in "C:\Windows". To examine the files and directories in "C:\Windows", use an pwszFileSpec of "C:\Windows*".

Be aware that some other thread or process could create or delete a file with this name between the time you query for the result and the time you act on the information. If this is a potential concern for your application, one possible solution is to use the CreateFile function with CREATE_NEW (which fails if the file exists) or OPEN_EXISTING (which fails if the file does not exist).

AfxFolderExists

Searches a directory for a file or subdirectory with a name that matches a specific name (or partial name if wildcards are used).

FUNCTION AfxFolderExists (BYVAL pwszFileSpec AS WSTRING PTR) AS BOOLEAN

Return value

Boolean. TRUE if the specified file exist or FALSE otherwise.

Remarks

Prepending the string "\\?\" does not allow access to the root directory.

On network shares, you can use an pwszFileSpec in the form of the following: "\\server\service\*". However, you cannot use an pwszFileSpec that points to the share itself; for example, "\\server\service" is not valid.

To examine a directory that is not a root directory, use the path to that directory, without a trailing backslash. For example, an argument of "C:\Windows" returns information about the directory "C:\Windows", not about a directory or file in "C:\Windows". To examine the files and directories in "C:\Windows", use an pwszFileSpec of "C:\Windows\*".

Be aware that some other thread or process could create or delete a file with this name between the time you query for the result and the time you act on the information. If this is a potential concern for your application, one possible solution is to use the CreateFile function with CREATE_NEW (which fails if the file exists) or OPEN_EXISTING (which fails if the file does not exist).

AfxGetFileSize / AfxFileLen

Returns the size in bytes of the specified file.

FUNCTION AfxGetFileSize (BYREF wszFileSpec AS WSTRING) AS ULONGLONG
FUNCTION AfxFileLen (BYREF wszFileSpec AS WSTRING) AS ULONGLONG

Return value

The size in bytes of the file on success, or 0 on failure.

AfxExePath / AfxGetExePath

Returns the path of the program which is currently executing.

FUNCTION AfxExePath () AS CWSTR
FUNCTION AfxGetExePath () AS CWSTR

Remarks

Unicode replacement for Free Basic's ExePath function. The path name has not a trailing backslash, except if it is a drive, e.g. "C:".

AfxGetExePathName

Returns the path of the program which is currently executing.

FUNCTION AfxGetExePathName () AS CWSTR

Remarks

The path name has a trailing backslash.

AfxGetDriveType

Determines whether a disk drive is a removable, fixed, CD-ROM, RAM disk, or network drive.

FUNCTION AfxGetDriveType (BYVAL lpRootPathName AS LPCWSTR) as UINT

Return value

DRIVE_UNKNOWN (0), DRIVE_NO_ROOT_DIR (1), DRIVE_REMOVABLE (2), DRIVE_FIXED(3), DRIVE_REMOTE (4), DRIVE_CDROM (5), DRIVE_RAMDISK (6).

AfxGetExeFileExt

Parses a path/filename and returns the extension portion of the path/file name.

FUNCTION AfxGetExeFileExt () AS CWSTR

Return value

The extension portion of the file name. That is the last period (.) in the string plus the text to the right of it.

AfxGetExeFileName

Returns the file name of the program which is currently executing.

FUNCTION AfxGetExeFileName () AS CWSTR

AfxGetExeFileNameX

Returns the file name and extension of the program which is currently executing.

FUNCTION AfxGetExeFileNameX () AS CWSTR

AfxGetExeFullPath

Returns the complete drive, path, file name, and extension of the program which is currently executing.

FUNCTION AfxGetExeFullPath () AS CWSTR

AfxGetFileExt

Parses a path/filename and returns the extension portion of the path/file name. That is the last period (.) in the string plus the text to the right of it.

FUNCTION AfxGetFileExt (BYREF wszPath AS WSTRING) AS CWSTR

AfxGetFileCreationTime

Returns the time the file was created, in FILETIME format.

FUNCTION AfxGetFileCreationTime (BYREF wszFileSpec AS WSTRING, BYVAL bUTC AS BOOLEAN = TRUE) AS FILETIME

AfxGetFileLastAccessTime

Returns the time the file was accessed, in FILETIME format.

FUNCTION AfxGetFileLastAccessTime (BYREF wszFileSpec AS WSTRING, BYVAL bUTC AS BOOLEAN = TRUE) AS FILETIME

AfxGetFileLastWriteTime

Returns the time the file was last written to, truncated, or overwritten, in FILETIME format.

FUNCTION AfxGetFileLastWriteTime (BYREF wszFileSpec AS WSTRING, BYVAL bUTC AS BOOLEAN = TRUE) AS FILETIME

AfxGetFileName

Parses a path/filename and returns the file name portion. That is the text to the right of the last backslash () or colon (:), ending just before the last period (.).

FUNCTION AfxGetFileName (BYREF wszPath AS WSTRING) AS CWSTR

AfxGetFileNameX

Parses a path/filename and returns the file name and extension portion. That is the text to the right of the last backslash (\) or colon (:).

FUNCTION AfxGetFileNameX (BYREF wszPath AS WSTRING) AS CWSTR

AfxGetFileVersion

Retrieves the version of the specified file multiplied by 100, e.g. 601 for version 6.01.

FUNCTION AfxGetFileVersion (BYVAL pwszFileName AS WSTRING PTR) AS DWORD

AfxGetFolderName

Returns a string containing the name of the folder for a specified path, i.e. the path minus the file name.

FUNCTION AfxGetFolderName (BYREF wszPath AS WSTRING) AS CWSTR

AfxGetKnowFolderPath

Retrieves the path of an special folder.

FUNCTION AfxGetKnowFolderPath (BYVAL rfid AS CONST KNOWNFOLDERID CONST PTR, _
   BYVAL dwFlags AS DWORD = 0, BYVAL hToken AS HANDLE = NULL) AS CWSTR

Return value

The path of the requested folder on success, or an empty string on failure.

Remarks

Requires Windows Vista/Windows 7 or superior.

For a list of KNOWNFOLDERID constants see: KNOWNFOLDERID

Usage example

AfxGetKnowFolderPath(@FOLDERID_CommonPrograms)

AfxGetLongPathName

Retrieves the short path form of the specified path.

FUNCTION AfxGetLongPathName (BYREF wszPath AS WSTRING) AS CWSTR

AfxGetPathName

Parses a path/filename and returns the path portion. That is the text up to and including the last backslash () or colon (:).

FUNCTION AfxGetPathName (BYREF wszPath AS WSTRING) AS CWSTR

AfxGetShortPathName

Retrieves the short path form of the specified path.

FUNCTION AfxGetShortPathName (BYREF wszPath AS WSTRING) AS CWSTR

AfxGetSpecialFolderLocation

Retrieves the path of a special folder.

FUNCTION AfxGetSpecialFolderLocation (BYVAL nFolder AS LONG) AS CWSTR

Remarks

For a list of CSIDL values see: CSIDL

AfxGetSystemDllPath

Retrieves the fully qualified path for the file that contains the specified module.

FUNCTION AfxGetSystemDllPath (BYREF wszDllName AS WSTRING) AS CWSTR

Remarks

To locate the file for a module that was loaded by another process, use the GetModuleFileNameEx function.

AfxGetWinDir

Retrieves the path of the Windows directory. This path does not end with a backslash unless the Windows directory is the root directory. For example, if the Windows directory is named Windows on drive C, the path of the Windows directory retrieved by this function is C:\Windows. If the system was installed in the root directory of drive C, the path retrieved is C:\.

FUNCTION AfxGetWinDir () AS CWSTR

AfxIsCompressedFile

Returns True if the specified file or directory is compressed; False if it is not.

FUNCTION AfxIsCompressedFile (BYREF wszFileSpec AS WSTRING) AS BOOLEAN

AfxIsEncryptedFile

Returns True if the specified file or directory is encrypted; False if it is not.

FUNCTION AfxIsEncryptedFile (BYREF wszFileSpec AS WSTRING) AS BOOLEAN

AfxIsFolder

Returns True if the specified path is a folder; False if it is not.

FUNCTION AfxIsFolder (BYREF wszFileSpec AS WSTRING) AS BOOLEAN

AfxIsHiddenFile

Returns True if the specified path is a hidden file or directory; False if it is not.

FUNCTION AfxIsHiddenFile (BYREF wszFileSpec AS WSTRING) AS BOOLEAN

AfxIsNormalFile

Returns True if the specified path is a normal file (a file that does not have other attributes set); False if it is not.

FUNCTION AfxIsNormalFile (BYREF wszFileSpec AS WSTRING) AS BOOLEAN

AfxIsNotContentIndexedFile

Returns TRUE if the specified file or directory is not to be indexed by the content indexing service; FALSE, otherwise.

FUNCTION AfxIsNotContentIndexedFile (BYREF wszFileSpec AS WSTRING) AS BOOLEAN

AfxIsOfflineFile

Returns TRUE if the specified file file is not available immediately; FALSE, otherwise.

FUNCTION AfxIsOfflineFile (BYREF wszFileSpec AS WSTRING) AS BOOLEAN

AfxIsReadOnlyFile

Returns True if the specified path is a read only file; False if it is not.

FUNCTION AfxIsReadOnlyFile (BYREF wszFileSpec AS WSTRING) AS BOOLEAN

AfxIsReparsePointFile

Returns TRUE if the specified path is a file or directory that has an associated reparse point, or a file that is a symbolic link.; FALSE, otherwise.

FUNCTION AfxIsReparsePointFile (BYREF wszFileSpec AS WSTRING) AS BOOLEAN

AfxIsSparseFile

Returns TRUE if the specified path is a sparse file; FALSE, otherwise.

FUNCTION AfxIsSparseFile (BYREF wszFileSpec AS WSTRING) AS BOOLEAN

AfxIsSystemFile

Returns True if the specified path is a system file; False if it is not.

FUNCTION AfxIsSystemFile (BYREF wszFileSpec AS WSTRING) AS BOOLEAN

AfxIsTemporaryFile

Returns True if the specified path is a temporary file; False if it is not.

FUNCTION AfxIsTemporaryFile (BYREF wszFileSpec AS WSTRING) AS BOOLEAN

AfxFileScan

Scans a text file ans returns the number of occurrences of the specified delimiter.

FUNCTION AfxFileScanA (BYREF wszFileName AS WSTRING, BYREF Delimiter AS ZSTRING = CHR(13, 10)) AS DWORD
FUNCTION AfxFileScanW (BYREF wszFileName AS WSTRING, BYREF Delimiter AS WSTRING = CHR(13, 10)) AS DWORD

Remarks

Use AfxFileScanA for ansi text files and AfxFileScanW for unicode text files.

AfxFileReadAllLines

Reads all the lines of the specified file into a safe array.

FUNCTION AfxFileReadAllLinesA (BYREF wszFileName AS WSTRING, BYREF Delimiter AS ZSTRING = CHR(13, 10)) AS CSafeArray
FUNCTION AfxFileReadAllLinesW (BYREF wszFileName AS WSTRING, BYREF Delimiter AS WSTRING = CHR(13, 10)) AS CSafeArray

Remarks

Use AfxFileReadAllLinesA for ansi text files and AfxFileReadAllLinesW for unicode text files.

Because it returns a safe array, this function is located in the CSafeArray.inc include file.

AfxSaveTempFile

Saves the contents of a string buffer in a temporary file.

FUNCTION AfxSaveTempFile (BYVAL pwszBuffer AS WSTRING PTR, BYREF wszExtension AS WSTRING) AS CWSTR

Remarks

Temporary files whose names have been created by this function are not automatically deleted. To delete these files call AfxDeleteFile.

AfxPathAddBackSlash

Adds a backslash to the end of a string to create the correct syntax for a path. If the source path already has a trailing backslash, no backslash will be added.

FUNCTION AfxPathAddBackSlash (BYREF wszPath AS CONST WSTRING) AS CWSTR

Return value

The changed path.

Usage example

DIM cws AS CWSTR = AfxPathAddBackSlash("C:\dir_name\dir_name\file_name")

AfxPathAddExtension

Adds a file name extension to a path string.

FUNCTION AfxPathAddExtension (BYREF wszPath AS CONST WSTRING, BYVAL pwszExt AS WSTRING PTR = NULL) AS CWSTR

Return value

The changed path.

Remarks

If there is already a file name extension present, no extension will be added. If the wszPath is an empty string, the result will be the file name extension only. If wszExtension is an empty string, an ".exe" extension will be added.

Usage examples

DIM cws AS CWSTR = AfxPathAddExtension("file") ' output: file.exe
DIM cws AS CWSTR = AfxPathAddExtension("file.doc") ' output: file.doc
DIM cws AS CWSTR = AfxPathAddExtension("file", ".txt") ' output: file.txt
DIM cws AS CWSTR = AfxPathAddExtension("", ".txt") ' output: .txt

AfxPathAppend

Appends one path to the end of another.

FUNCTION AfxPathAppend (BYREF wszPath AS CONST WSTRING, BYREF wszMore AS CONST WSTRING) AS CWSTR

Return value

The changed path.

Remarks

This function automatically inserts a backslash between the two strings, if one is not already present.

The path supplied in wszPath cannot begin with "..\" or ".\" to produce a relative path string. If present, those periods are stripped from the output string. For example, appending "path3" to "..\path1\path2" results in an output of "\path1\path2\path3" rather than "..\path1\path2\path3".

Usage example

DIM cws AS CWSTR = AfxPathAppend("name_1\name_2", "name_3")

AfxPathBuildRoot

Creates a root path from a given drive number.

FUNCTION AfxPathBuildRoot (BYVAL nDrive AS LONG) AS CWSTR

Return value

The root path. If the call fails for any reason (for example, an invalid drive number), an empty string is returned.

Usage example

DIM cws AS CWSTR = AfxPathBuildRoot(2) ' output: C:\

AfxPathCanonicalize

Removes elements of a file path according to special strings inserted into that path.

FUNCTION AfxPathCanonicalize (BYREF wszPath AS CONST WSTRING) AS CWSTR

Return value

The canonicalized path.

Remarks

This function allows the user to specify what to remove from a path by inserting special character sequences into the path. The ".." sequence indicates to remove a path segment from the current position to the previous path segment. The "." sequence indicates to skip over the next path segment to the following path segment. The root segment of the path cannot be removed.

If there are more ".." sequences than there are path segments, the contents of the returned string contains just the root, "\".

Usage example

DIM cws AS CWSTR = AfxPathCanonicalize("A:\name_1\.\name_2\..\sname_3") ' output: A:\name_1\name_3
DIM cws AS CWSTR = AfxPathCanonicalize("A:\name_1\..\name_2\.\name_3") ' output: A:\name_2\name_3
DIM cws AS CWSTR = AfxPathCanonicalize("A:\name_1\name_2\.\name_3\..\name_4") ' output: A:\name_1\name_2\name_4
DIM cws AS CWSTR = AfxPathCanonicalize("A:\name_1\.\name_2\.\name_3\..\name_4\..") ' output: A:\name_1\name_2
DIM cws AS CWSTR = AfxPathCanonicalize("C:\..") ' output: C:\

AfxPathCombine

Concatenates two strings that represent properly formed paths into one path; also concatenates any relative path elements.

FUNCTION AfxPathCombine (BYREF wszDir AS CONST WSTRING, BYREF wszFile AS CONST WSTRING) AS CWSTR

Return value

The concatenated path if successful, or an empty string otherwise.

Remarks

The directory path should be in the form of A:,B:, ..., Z:. The file path should be in a correct form that represents the file part of the path. The file path must not be null, and if it ends with a backslash, the backslash will be maintained.

Usage example

DIM cws AS CWSTR = AfxPathCombine("C:", "One\Two\Three") ' output: C:\One\Two\Three

AfxPathCommonPrefix

Compares two paths to determine if they share a common prefix. A prefix is one of these types: "C:\", ".", "..", "..\".

FUNCTION AfxPathCommonPrefix (BYREF wszFile1 AS CONST WSTRING, BYREF wszFile2 AS CONST WSTRING) AS CWSTR

Return value

The common prefix.

Usage example

DIM cws AS CWSTR = AfxPathCommonPrefix("C:\win\desktop\temp.txt", "c:\win\tray\sample.txt")

AfxPathCompactPath

Truncates a file path to fit within a given pixel width by replacing path components with ellipses.

FUNCTION AfxPathCompactPath (BYVAL hDC AS HDC, BYREF wszPath AS CONST WSTRING, BYVAL dx AS DWORD) AS CWSTR

Return value

The compacted path.

Remarks

This function uses the font currently selected in hDC to calculate the width of the text. This function will not compact the path beyond the base file name preceded by ellipses.

Usage example

DIM cws AS CWSTR = AfxPathCompactPath(NULL, "C:\path1\path2\sample.txt", 180)

AfxPathCompactPathEx

Truncates a path to fit within a certain number of characters by replacing path components with ellipses.

FUNCTION AfxPathCompactPathEx (BYREF wszPath AS CONST WSTRING, BYVAL cchMax AS DWORD) AS CWSTR

Return value

The compacted path.

Remarks

The '/' separator will be used instead of '\' if the original string used it. If wszPath points to a file name that is too long, instead of a path, the file name will be truncated to cchMax characters, including the ellipsis and the terminating NULL character. For example, if the input file name is "My Filename" and cchMax is 10, AfxPathCompactPathEx will return "My Fil...".

Usage example

DIM cws AS CWSTR = AfxPathCompactPathEx("c:\test\My Filename", 18)

AfxPathCreateFromUrl

Converts a file URL to a Microsoft MS-DOS path.

FUNCTION AfxPathCreateFromUrl (BYREF wszUrl AS CONST WSTRING) AS CWSTR

Return value

The MS-DOS path.

Usage example

DIM cws AS CWSTR = AfxPathCreateFromUrl("file:///C:/Documents%20and%20Settings/URIS.txt")

AfxPathFileExists

Determines whether a path to a file system object such as a file or directory is valid.

FUNCTION AfxPathFileExists (BYREF wszPath AS WSTRING) AS BOOLEAN

Return value

Returns TRUE if the file exists, or FALSE otherwise.

Remarks

This function tests the validity of the path.

A path specified by Universal Naming Convention (UNC) is limited to a file only; that is, \\server\share\file is permitted. A UNC path to a server or server share is not permitted; that is, \\server or \\server\share. This function returns FALSE if a mounted remote drive is out of service.

AfxPathFindExtension

Searches a path for an extension.

FUNCTION AfxPathFindExtension (BYREF wszPath AS CONST WSTRING) AS CWSTR

Return value

The file name extension.

Remarks

Note that a valid file name extension cannot contain a space.

Usage example

DIM cws AS CWSTR = AfxPathFindExtension("C:\TEST\filetxt")

AfxPathFindFileName

Searches a path for a file name.

FUNCTION AfxPathFindFileName (BYREF wszPath AS CONST WSTRING) AS CWSTR

Return value

The file name.

AfxPathFindNextComponent

Searches a path for a file name.

FUNCTION AfxPathFindNextComponent (BYREF wszPath AS CONST WSTRING) AS CWSTR

Return value

The truncated path.

Remarks

AfxPathFindNextComponent walks a path string until it encounters a backslash ("\"), ignores everything up to that point including the backslash, and returns the rest of the path. Therefore, if a path begins with a backslash (such as \path1\path2), the function simply removes the initial backslash and returns the rest (path1\path2).

Usage example

DIM cws AS CWSTR = AfxPathFindNextComponent("C:\TEST\file.txt")

AfxPathFindOnPath

Searches for a file.

FUNCTION AfxPathFindOnPath (BYREF wszFile AS CONST WSTRING, _
   BYVAL ppwszOtherDirs AS WSTRING PTR PTR = NULL) AS CWSTR

Return value

The fully-qualified path name on success or an empty string on failure.

Remarks

AfxPathFindOnPath searches for the file specified by wszFile. If no directories are specified in ppwszOtherDirs, it attempts to find the file by searching standard directories such as System32 and the directories specified in the PATH environment variable. To expedite the process or enable AfxPathFindOnPath to search a wider range of directories, use the ppwszOtherDirs parameter to specify one or more directories to be searched first. If more than one file has the name specified by wszFile, AfxPathFindOnPath returns the first instance it finds.

AfxPathFindSuffixArray

Determines whether a given file name has one of a list of suffixes.

FUNCTION AfxPathFindSuffixArray (BYREF wszPath AS WSTRING, BYVAL apwszSuffix AS WSTRING PTR PTR, _
   BYVAL iArraySize AS LONG) AS CWSTR

Return value

The matching suffix if successful, or an empty string if bstrPath does not end with one of the specified suffixes.

Remarks

This function uses a case-sensitive comparison. The suffix must match exactly.

AfxPathGetArgs

Finds the command line arguments within a given path.

FUNCTION AfxPathGetArgs (BYREF wszPath AS CONST WSTRING) AS CWSTR

Return value

A string that contains the arguments portion of the path if successful or an empty string if there are no arguments in the path.

Remarks

This function should not be used on generic command path templates (from users or the registry), but rather should be used only on templates that the application knows to be well formed.

AfxPathGetCharType

Determines the type of character in relation to a path.

FUNCTION AfxPathGetCharType (BYREF wszCh AS CONST WSTRING) AS UINT

Return value

Returns one or more of the following values that define the type of character.

AfxPathGetDriveNumber

Searches a path for a drive letter within the range of 'A' to 'Z' and returns the corresponding drive number.

FUNCTION AfxPathGetDriveNumber (BYREF wszPath AS CONST WSTRING) AS LONG

Return value

Returns 0 through 25 (corresponding to 'A' through 'Z') if the path has a drive letter, or -1 otherwise.

Usage example

DIM n AS LONG = AfxPathGetDriveNumber("C:\TEST\bar.txt") ' output: 2

AfxPathIsContentType

Determines if a file's registered content type matches the specified content type. This function obtains the content type for the specified file type and compares that string with the wszContentType. The comparison is not case-sensitive.

FUNCTION AfxPathIsContentType (BYREF wszPath AS CONST WSTRING, _
   BYREF wszContentType AS CONST WSTRING) AS BOOLEAN

Return value

Returns nonzero if the file's registered content type matches wszContentType, or zero otherwise.

Usage example

DIM b AS BOOLEAN = AfxPathIsContentType("C:\TEST\bar.txt", "text/plain") ' output: true
DIM b AS BOOLEAN = AfxPathIsContentType("C:\TEST\bar.txt", "image/gif") ' output: false

AfxPathIsDirectory

Verifies that a path is a valid directory.

FUNCTION AfxPathIsDirectory (BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns TRUE if the path is a valid directory (FILE_ATTRIBUTE_DIRECTORY is set), or FALSE otherwise.

AfxPathIsDirectoryEmpty

Determines whether a specified path is an empty directory.

FUNCTION AfxPathIsDirectoryEmpty (BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns TRUE if wszPath is an empty directory. Returns FALSE if wszPath is not a directory, or if it contains at least one file other than "." or "..".

Remarks

"C:" is considered a directory.

AfxPathIsFileSpec

Searches a path for any path-delimiting characters (for example, ':' or '\' ). If there are no path-delimiting characters present, the path is considered to be a File Spec path.

FUNCTION AfxPathIsFileSpec (BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns TRUE if there are no path-delimiting characters within the path, or FALSE if there are path-delimiting characters.

AfxPathIsHTMLFile

Determines if a file is an HTML file. The determination is made based on the content type that is registered for the file's extension.

FUNCTION AfxPathIsHTMLFile (BYREF wszFile AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if the file is an HTML file, or False otherwise.

AfxPathIsLFNFileSpec

Determines whether a file name is in long format.

FUNCTION AfxPathIsLFNFileSpec (BYREF wszName AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if wszName exceeds the number of characters allowed by the 8.3 format, or False otherwise.

AfxPathIsNetworkPath

Determines whether a path string represents a network resource.

FUNCTION AfxPathIsNetworkPath (BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if the string represents a network resource, or False otherwise.

AfxPathIsPrefix

Searches a path to determine if it contains a valid prefix of the type passed by wszPrefix. A prefix is one of these types: "C:\", ".", "..", "..\".

FUNCTION AfxPathIsPrefix (BYREF wszPrefix AS CONST WSTRING, BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if the compared path is the full prefix for the path, or False otherwise.

AfxPathIsRelative

Searches a path and determines if it is relative.

FUNCTION AfxPathIsRelative (BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if the path is relative, or False if it is absolute.

AfxPathIsRoot

Parses a path to determine if it is a directory root.

FUNCTION AfxPathIsRoot (BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if the specified path is a root, or False otherwise.

Remarks

Returns True for paths such as "\", "X:\" or "\\server\share". Paths such as "..\path2" or "\\server\" return FALSE.

AfxPathIsSameRoot

Compares two paths to determine if they have a common root component.

FUNCTION AfxPathIsSameRoot (BYREF wszPath1 AS CONST WSTRING, BYREF wszPath2 AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if both strings have the same root component, or False otherwise. If wszPath1 contains only the server and share, this function also returns False.

AfxPathIsSystemFolder

Determines if an existing folder contains the attributes that make it a system folder. Alternately, this function indicates if certain attributes qualify a folder to be a system folder.

FUNCTION AfxPathIsSystemFolder (BYREF wszPath AS CONST WSTRING, BYVAL dwAttrb AS DWORD) AS BOOLEAN

Return value

Returns True if the wszPath or dwAttrb represent a system folder, or False otherwise.

AfxPathIsUNC

Determines if the string is a valid Universal Naming Convention (UNC) for a server and share path.

FUNCTION AfxPathIsUNC (BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if the string is a valid UNC path, or False otherwise.

AfxPathIsUNCServer

Determines if a string is a valid Universal Naming Convention (UNC) for a server path only.

FUNCTION AfxPathIsUNCServer (BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if the string is a valid UNC path for a server only (no share name), or False otherwise.

AfxPathIsUNCServerShare

Determines if a string is a valid Universal Naming Convention (UNC) share path, \\server\share.

FUNCTION AfxPathIsUNCServerShare (BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if the string is in the form \\server\share, or False otherwise.

AfxPathIsURL

Tests a given string to determine if it conforms to a valid URL format.

FUNCTION AfxPathIsURL (BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if wszPath has a valid URL format, or Fañse otherwise.

Remarks

This function does not verify that the path points to an existing site—only that it has a valid URL format.

AfxPathMakePretty

Converts a path to all lowercase characters to give the path a consistent appearance.

FUNCTION AfxPathMakePretty (BYREF wszPath AS CONST WSTRING) AS CWSTR

Return value

The changed path.

Remarks

This function only operates on paths that are entirely uppercase. For example: C:\WINDOWS will be converted to c:\windows, but c:\Windows will not be changed.

AfxPathMakeSystemFolder

Gives an existing folder the proper attributes to become a system folder.

FUNCTION AfxPathMakeSystemFolder (BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if successful, or False otherwise.

AfxPathMatchSpec

Searches a string using a Microsoft MS-DOS wild card match type.

FUNCTION AfxPathMatchSpec (BYREF wszFile AS CONST WSTRING, BYREF wszSpec AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if the string matches, or False otherwise.

AfxPathMatchSpecEx

Searches a path to determine whether it contains a file of a specified file type extension.

FUNCTION AfxPathMatchSpecEx (BYREF wszFile AS CONST WSTRING, _
   BYREF wszSpec AS CONST WSTRING, BYVAL dwFlags AS DWORD) AS BOOLEAN

Return value

Returns one of the following values:

AfxPathParseIconLocation

Parses a file location string that contains a file location and icon index, and returns separate values.

FUNCTION AfxPathParseIconLocation (BYREF wszIconFile AS CONST WSTRING) AS CWSTR

Return value

Returns the valid icon index value.

Remarks

This function is useful for taking a DefaultIcon value retrieved from the registry by SHGetValue and separating the icon index from the path.

Usage example

DIM wszIconLocation AS CWSTR = AfxPathParseIconLocation("C:\TEST\sample.txt,3")

AfxPathQuoteSpaces

Searches a path for spaces. If spaces are found, the entire path is enclosed in quotation marks.

FUNCTION AfxPathQuoteSpaces (BYREF wszPath AS CONST WSTRING) AS CWSTR

Return value

True if spaces were found; otherwise, False.

AfxPathRelativePathTo

Creates a relative path from one file or folder to another.

FUNCTION AfxPathRelativePathTo (BYREF wszFrom AS CONST WSTRING, BYVAL dwAttrFrom AS DWORD, _
   BYREF wszTo AS CONST WSTRING, BYVAL dwAttrTo AS DWORD) AS CWSTR

Return value

Returns True if successful, or False otherwise.

Remarks

This function takes a pair of paths and generates a relative path from one to the other. The paths do not have to be fully-qualified, but they must have a common prefix, or the function will fail and return False.

For example, let the starting point, wszFrom, be "c:\FolderA\FolderB\FolderC", and the ending point, wszTo, be "c:\FolderA\FolderD\FolderE". AfxPathRelativePathTo will return the relative path from wszFrom to wszTo as: "..\..\FolderD\FolderE". You will get the same result if you set wszFrom to "\FolderA\FolderB\FolderC" and wszTo to "\FolderA\FolderD\FolderE". On the other hand, "c:\FolderA\FolderB" and "a:\FolderA\FolderD do not share a common prefix, and the function will fail. Note that "\\" is not considered a prefix and is ignored. If you set wszFrom to "\\FolderA\FolderB", and wszTo to "\\FolderC\FolderD", the function will fail.

AfxPathRemoveArgs

Removes any arguments from a given path.

FUNCTION AfxPathRemoveArgs (BYREF wszPath AS CONST WSTRING) AS CWSTR

Return value

The changed path.

Remarks

This function should not be used on generic command path templates (from users or the registry), but rather it should be used only on templates that the application knows to be well formed.

AfxPathRemoveBackslash

Removes the trailing backslash from a given path.

FUNCTION AfxPathRemoveBackslash (BYREF wszPath AS CONST WSTRING) AS CWSTR

Return value

The changed path.

AfxPathRemoveBlanks

Removes all leading and trailing spaces from a string.

FUNCTION AfxPathRemoveBlanks (BYREF wszPath AS CONST WSTRING) AS CWSTR

Return value

The changed path.

AfxPathRemoveExtension

Removes the file name extension from a path, if one is present.

FUNCTION AfxPathRemoveExtension (BYREF wszPath AS CONST WSTRING) AS CWSTR

Return value

The changed path.

AfxPathRemoveFileSpec

Removes the trailing file name and backslash from a path, if they are present.

FUNCTION AfxPathRemoveFileSpec (BYREF wszPath AS CONST WSTRING) AS CWSTR

Return value

The changed path.

AfxPathRenameExtension

Replaces the extension of a file name with a new extension. If the file name does not contain an extension, the extension will be attached to the end of the string.

FUNCTION AfxPathRenameExtension (BYREF wszPath AS CONST WSTRING, BYREF wszExt AS CONST WSTRING) AS CWSTR

Return value

The new path. If the new path and extension would exceed MAX_PATH characters, the path won't be changed.

AfxPathSearchAndQualify

Determines if a given path is correctly formatted and fully qualified.

FUNCTION AfxPathSearchAndQualify (BYREF wszPath AS CONST WSTRING, BYREF wszFullyQualifiedPath AS CONST WSTRING, _
   BYVAL cchFullyQualifiedPath AS DWORD) AS BOOLEAN

Return value

Returns True if the path is qualified, or False otherwise.

AfxPathSetDlgItemPath

Sets the text of a child control in a window or dialog box, using AfxCompactPath to ensure the path fits in the control.

SUB AfxPathSetDlgItemPath (BYVAL hDlg AS HWND, BYVAL cID AS LONG, BYREF wszPath AS WSTRING)

AfxPathSkipRoot

Parses a path, ignoring the drive letter or Universal Naming Convention (UNC) server/share path elements.

FUNCTION AfxPathSkipRoot (BYREF wszPath AS CONST WSTRING) AS CWSTR

Return value

The changed path.

AfxPathStripPath

Removes the path portion of a fully qualified path and file.

FUNCTION AfxPathStripPath (BYREF wszPath AS CONST WSTRING) AS CWSTR

Return value

The changed path.

AfxPathStripToRoot

Removes all parts of the path except for the root information.

FUNCTION AfxPathStripToRoot (BYREF wszRoot AS CONST WSTRING) AS CWSTR

Return value

Returns a string that contains only the root information taken from that path.

AfxPathUndecorate

Removes the decoration from a path string.

FUNCTION AfxPathUndecorate (BYREF wszPath AS CONST WSTRING) AS CWSTR

Return value

The undecorated string.

Remarks

A decoration consists of a pair of square brackets with one or more digits in between, inserted immediately after the base name and before the file name extension.

Example

The following table illustrates how strings are modified by AfxPathUndecorate.

AfxPathUnExpandEnvStrings

Replaces certain folder names in a fully-qualified path with their associated environment string.

FUNCTION AfxPathUnExpandEnvStrings (BYREF wszPath AS CONST WSTRING) AS CWSTR

Return value

The unexpanded string.

AfxPathUnmakeSystemFolder

Removes the attributes from a folder that make it a system folder. This folder must actually exist in the file system.

FUNCTION AfxPathUnmakeSystemFolder (BYREF wszPath AS CONST WSTRING) AS BOOLEAN

Return value

Returns nonzero if successful, or zero otherwise.

AfxPathUnquoteSpaces

Removes quotes from the beginning and end of a path.

FUNCTION AfxPathUnquoteSpaces (BYREF wszPath AS CONST WSTRING) AS CWSTR

Return value

The unquoted path.

AfxUrlApplyScheme

Determines a scheme for a specified URL string, and returns a string with an appropriate prefix.

FUNCTION AfxUrlApplyScheme (BYREF wszUrl AS WSTRING, BYVAL dwFlags AS DWORD) AS CWSTR

Return value

The changed url.

Remarks

If the URL has a valid scheme, the string will not be modified. However, almost any combination of two or more characters followed by a colon will be parsed as a scheme. Valid characters include some common punctuation marks, such as ".". If your input string fits this description, AfxUrlApplyScheme may treat it as valid and not apply a scheme. To force the function to apply a scheme to a URL, set the URL_APPLY_FORCEAPPLY and URL_APPLY_DEFAULT flags in dwFlags. This combination of flags forces the function to apply a scheme to the URL. Typically, the function will not be able to determine a valid scheme. The second flag guarantees that, if no valid scheme can be determined, the function will apply the default scheme to the URL.

AfxUrlCanonicalize

Converts a URL string into canonical form.

FUNCTION AfxUrlCanonicalize (BYREF wszUrl AS WSTRING, BYVAL dwFlags AS DWORD) AS CWSTR

Return value

The canonicalized url.

Remarks

This function performs such tasks as replacing unsafe characters with their escape sequences and collapsing sequences like "..\...".

If a URL string contains "/../" or "/./", AfxUrlCanonicalize normally treats the characters as indicating navigation in the URL hierarchy. The function simplifies the URLs before combining them. For instance "/hello/cruel/../world" is simplified to "/hello/world". If the URL_DONT_SIMPLIFY flag is set in dwFlags, the function does not simplify URLs. In this case, "/hello/cruel/../world" is left as it is.

AfxUrlCombine

When provided with a relative URL and its base, returns a URL in canonical form.

FUNCTION AfxUrlCombine (BYREF wszBase AS WSTRING, BYREF wszRelative AS WSTRING, BYVAL dwFlags AS DWORD) AS CWSTR

Return value

The canonicalized url.

Remarks

Items between slashes are treated as hierarchical identifiers; the last item specifies the document itself. You must enter a slash (/) after the document name to append more items; otherwise, AfxUrlCombine changes one document for another.

If a URL string contains '/../' or '/./', AfxUrlCombine usually treats the characters as if they indicated navigation in the URL hierarchy. The function simplifies the URLs before combining them. For instance, "/hello/cruel/../world" is simplified to "/hello/world". If the URL_DONT_SIMPLIFY flag is set in dwFlags, the function does not simplify URLs. In this case, "/hello/cruel/../world" is left as it is.

AfxUrlCompare

Makes a case-sensitive comparison of two URL strings.

FUNCTION AfxUrlCompare (BYREF wszUrl1 AS CONST WSTRING, BYREF wszUrl2 AS CONST WSTRING, _
   BYVAL fIgnoreSlash AS LONG) AS LONG

Return value

Returns zero if the two strings are equal. The function will also return zero if fIgnoreSlash is set to TRUE and one of the strings has a trailing '\' character. The function returns a negative integer if the string pointed to by wszUrl1 is less than the string pointed to by wszUrl2. Otherwise, it returns a positive integer.

Remarks

For best results, you should first canonicalize the URLs with AfxUrlCanonicalize. Then, compare the canonicalized URLs with AfxUrlCompare.

AfxUrlCreateFromPath

Converts a Microsoft MS-DOS path to a canonicalized URL.

FUNCTION AfxUrlCreateFromPath (BYREF wszPath AS WSTRING) AS CWSTR

Return value

The canonicalized URL.

AfxUrlEscape

Converts characters in a URL that might be altered during transport across the Internet ("unsafe" characters) into their corresponding escape sequences.

FUNCTION AfxUrlEscape (BYREF wszUrl AS WSTRING, BYVAL dwFlags AS DWORD) AS CWSTR

Return value

The converted URL.

Remarks

For the purposes of this document, a typical URL is divided into three sections: the server, the segment, and the query. For example:

http://microsoft.com/test.asp?url=/example/abc.asp?frame=true#fragment

The server portion is "http://microsoft.com/". The trailing forward slash is considered part of the server portion.

The segment portion is any part of the path found following the server portion, but before the first # or ? character, in this case simply "test.asp".

The query portion is the remainder of the path from the first # or ? character (inclusive) to the end. In the example, it is "?url=/example/abc.asp?frame=true#fragment".

Unsafe characters are those characters that might be altered during transport across the Internet. This function converts unsafe characters into their equivalent "%xy" escape sequences. The following table shows unsafe characters and their escape sequences.

Use of the URL_ESCAPE_SEGMENT_ONLY flag also causes the conversion of the # (%23), ? (%3F), and / (%2F) characters.

By default, AfxUrlEscape ignores any text following a # or ? character. The URL_ESCAPE_SEGMENT_ONLY flag overrides this behavior by regarding the entire string as the segment. The URL_ESCAPE_SPACES_ONLY flag overrides this behavior, but only for space characters.

Security Warning: This function should be called from client applications only.

AfxUrlEscapeSpaces

Converts space characters into their corresponding escape sequence.

FUNCTION AfxUrlEscapeSpaces (BYREF wszUrl AS WSTRING) AS CWSTR

Return value

The converted URL.

AfxUrlFixup

Attempts to correct a URL whose protocol identifier is incorrect. For example, htttp will be changed to http.

FUNCTION AfxUrlFixup (BYREF wszUrl AS WSTRING) AS CWSTR

Return value

The converted URL.

Remarks

The AfxUrlFixup function recognizes the schemes specified by the URL_SCHEME enumeration.

Priority is given to the first character in the protocol identifier section so htp will be converted to http instead of ftp.

Notes

Do not use this function for deterministic data transformation. The heuristics used by AfxUrlFixup can change from one release to the next. The function should only be used to correct possibly invalid user input.

This function is available through Windows 7 and Windows Server 2008. It might be altered or unavailable in subsequent versions of Windows.

AfxUrlGetLocation

Retrieves the location from a URL.

FUNCTION AfxUrlGetLocation (BYREF wszUrl AS CONST WSTRING) AS CWSTR

Return value

A string with the location or an empty string.

Remarks

The location is the segment of the URL starting with a ? or # character. If a file URL has a query string, the returned string includes the query string.

AfxUrlGetPart

Accepts a URL string and returns a specified part of that URL.

FUNCTION AfxUrlGetPart (BYREF wszUrl AS WSTRING, _
   BYVAL dwPart AS DWORD, BYVAL dwFlags AS DWORD) AS CWSTR

Return value

A string with the specified part of that URL.

AfxUrlHash

Hashes a URL string.

FUNCTION AfxUrlHash (BYREF wszUrl AS WSTRING, BYVAL pbHash AS BYTE PTR, _
   BYVAL cbHash AS DWORD) AS HRESULT

Return value

If the function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

To hash a URL into a single byte, set cbHash = SIZEOF(BYTE) and pbHash = VARPTR(bHashedValue), where bHashedValue is a one-byte buffer.

To hash a URL into a DWORD, set cbHash = SIZEOF(DWORD) and pbHash = VARPTR(dwHashedValue), where dwHashedValue is a DWORD buffer.

AfxUrlIs

Tests whether or not a URL is a specified type.

FUNCTION AfxUrlIs (BYREF wszUrl AS WSTRING, BYVAL nUrlIs AS URLIS) AS BOOLEAN

Return value

For all but one of the URL types, AfxUrlIs returns True if the URL is the specified type, or False if not.

If AfxUrlIs is set to URLIS_APPLIABLE, AfxUrlIs will attempt to determine the URL scheme. If the function is able to determine a scheme, it returns True, or False otherwise.

AfxUrlIsFileUrl

Tests a URL to determine if it is a file URL.

FUNCTION AfxUrlIsFileUrl (BYREF wszUrl AS WSTRING) AS BOOLEAN

Return value

Returns True if the URL is a file URL, or False otherwise.

Remarks

A file URL has the form "File:// xxx".

AfxUrlIsNoHistory

Returns whether a URL is a URL that browsers typically do not include in navigation history.

FUNCTION AfxUrlIsNoHistory (BYREF wszUrl AS CONST WSTRING) AS BOOLEAN

Return value

Returns a True value if the URL is a URL that is not included in navigation history, or False otherwise.

Remarks

This function is equivalent to the following: AfxUrlIs(wszURL, URLIS_NOHISTORY)

AfxUrlIsOpaque

Returns whether a URL is opaque.

FUNCTION AfxUrlIsOpaque (BYVAL wszUrl AS CONST WSTRING) AS BOOLEAN

Return value

Returns True if the URL is opaque, or False otherwise.

Remarks

A URL that has a scheme that is not followed by two slashes (//) is opaque. For example, mailto:xyz@litwareinc.com is an opaque URL. Opaque URLs cannot be separated into the standard URL hierarchy. AfxUrlIsOpaque is equivalent to the following: AfxUrlIs(wszURL, URLIS_OPAQUE)

AfxUrlUnescape

Converts escape sequences back into ordinary characters.

FUNCTION AfxUrlUnescape (BYREF wszUrl AS WSTRING, BYVAL dwFlags AS DWORD) AS CWSTR

Return value

Returns S_OK (0) if successful or an HRESULT otherwise.

Remarks

An escape sequence has the form "%xy".

Input strings cannot be longer than INTERNET_MAX_URL_LENGTH.

AfxUrlUnescapeInPlace

Converts escape sequences back into ordinary characters and overwrites the original string.

FUNCTION AfxUrlUnescapeInPlace (BYREF wszUrl AS WSTRING, BYVAL dwFlags AS DWORD) AS HRESULT

Return value

Returns S_OK (0) if successful or an HRESULT otherwise.